Title Banner

Previous Book Contents Book Index Next

Inside Macintosh: QuickDraw GX Printing Extensions and Drivers /
Chapter 3 - Printer Drivers

About Printer Drivers

Macintosh system software uses device drivers to communicate information to hardware devices. A printer driver is a device driver--an independent software component that the system software uses to convert document data into printed output on a peripheral device such as a printer or plotter. In the QuickDraw GX environment, a printer driver sends QuickDraw GX data and instructions in a form specific to the printing device that it drives and manages the communications with that printing device.

Each printer driver has a Chooser interface through which the user can select communications parameters or special features of the driver. Each driver also displays status and alert information to the user through the Finder, as described in the section "Displaying Status Information and the Printing Alert Boxes" beginning on page 3-41.

QuickDraw GX allows the user to print documents to a different computer than is used to create the documents. This is often the case when a network includes a print server that several computers share. When the same computer is used, only one copy of your driver is required. When different computers are used, a copy of your printer driver must reside both on the computer that is sending the document to be printed and on the computer that is communicating with the printing device. The use of more than one copy of your driver is generally invisible to you, but understanding it does come into play because of how status and error conditions are handled in your driver. This is described in the section "Handling Status and Alert Conditions" beginning on page 3-9.

You need to develop a separate driver for each hardware device that has different characteristics. Developing a printer driver is different for each imaging system.

A printer driver consists of resources that define the driver to the printing system. A printer driver is a message handler in a message chain. QuickDraw GX communicates with a driver by sending printing messages down the message chain. A driver receives
a printing message by defining the set of messages it wishes to receive and act on. For example, a printer driver that supports raster printing devices overrides the messages for the raster imaging system.

Although you need to specify a fair amount of information in your printer driver resources, you can create drivers for many printing devices without writing very much code. QuickDraw GX provides default implementations of all of the tasks that a printer driver needs to accomplish, which means that you only need to override the printing messages that relate to specific or unique qualities of your printing device. For example, some PostScript printer drivers can use all of the default implementations of printing messages, with any device-specific parameters defined in the resource descriptions that you provide.

Each of the following sections describes a task that a QuickDraw GX printer driver needs to manage:

Each printing task is accomplished during one of the phases of printing, which are described in the chapter "Introduction to Printing Extensions and Drivers" in this book. Some of the printing tasks execute in the foreground and others execute in the background. A foreground task takes control of the computer, preempting the user from performing any other application tasks. A background task operates by taking control of the computer for brief periods of time while the application has relinquished time, allowing the user to continue working.

Writing Data to the Spool File

The first task that a QuickDraw GX printer driver needs to manage involves spooling
a document to disk. During spooling, which occurs in the foreground, the application writes document data to a spool file by sending an intermediate representation of the document (which can be a portable digital document) to disk. Spooling occurs when the application calls the GXStartJob function, which causes QuickDraw GX to send the GXStartJob message.

Spooling of the document data to the spool file is handled by five messages: GXCreateSpoolFile, GXSpoolPage, GXSpoolData, GXSpoolResource, and GXCompleteSpoolFile.

The QuickDraw GX default implementations of the spooling messages provide the basic spooling functionality. You generally override these messages in a printing extension or printer driver to add specific data handling, such as encrypting the data that is sent to the spool file. If you are taking advantage of the default handling of these spooling messages, you always need to forward the messages before or after adding your own functionality.

If you choose to totally override a spooling message, that is, you choose not to forward
it so that the default implementation can perform its tasks, you must handle all spooling on your own. This means that you must totally override all of the spooling messages and take care of writing the data to the spool file. You only need to do this if you are developing a driver that needs to create a custom spool-file format.

You can find a complete description of the interface and functionality of each of the spooling messages in the section "Spooling Messages" beginning on page 4-67 in the chapter "Printing Messages."

Spooling Translated QuickDraw Data in Print Files
When spooling a file that contains QuickDraw drawing commands, QuickDraw GX by default stores untranslated QuickDraw data in the print file. When the print file is despooled and imaged, QuickDraw GX then converts the data to QuickDraw GX shapes and prints them. If you want to force QuickDraw GX to translate QuickDraw data to QuickDraw GX shapes before spooling, you can override the GXFetchTaggedData message that QuickDraw GX sends at spooling time to fetch resource data of type 'pcfg'. Your override should forward the message, and then clear the highest-order bit of the data that is returned from the message. If the data's highest-order bit is cleared, QuickDraw GX translates and stores the data in the print file as QuickDraw GX shapes. For more information on QuickDraw data in print files, see the discussion of the 'pict' tag object in the advanced printing features chapter of Inside Macintosh: QuickDraw GX Printing.

Reading Data From the Spool File

During the first part of the imaging phase of printing, QuickDraw GX despools each document from disk. During despooling, which occurs in the background, your printer driver reads the spooled document from the spool-file. Depooling of the document data from the spool-file is handled by five messages, which are complementary to the spooling messages: GXCountPages, GXDespoolPage, GXDespoolData, GXDespoolResource, and GXCloseSpoolFile.

The QuickDraw GX default implementations of the despooling messages provide
the basic despooling functionality. You generally override these messages in a printing extension or printer driver to add specific data handling, such as decrypting the data that you encrypted in your overrides of the spooling messages. If you are taking advantage of the default handling of these despooling messages, you always need to forward the messages before or after adding your own functionality.

If you choose to totally override a despooling message, that is, you choose not to forward it so that the default implementation can perform its tasks, you must handle all despooling on your own. This means that you must totally override all of the despooling messages and take care of reading the data from the spool-file. As with spooling, you only need to do this if you are implementing a driver that needs to create a custom spool-file format.

You can find a complete description of the interface and functionality of each of the despooling messages in the section "Despooling Messages" beginning on page 4-74 in the chapter "Printing Messages."

Despooling Print Files Containing QuickDraw Picture Data
When a document containing QuickDraw imaging commands is spooled, QuickDraw GX by default saves the QuickDraw data for each page in a tag object of tag type 'pict' attached to a rectangle shape. If you examine the contents of a despooled file, note that the presence of a rectangle shape with such an attached tag object indicates the presence of QuickDraw picture data. For more information, see the discussion of the 'pict' tag object in the advanced printing features chapter of Inside Macintosh: QuickDraw GX Printing.

Converting QuickDraw GX Shapes

During the second part of the imaging phase of printing, your printer driver needs to convert the QuickDraw GX shape or shapes that compose each page into instructions that your printing device can use to produce the printed version of the page. This process of rendering each page into printable form takes place in the background. Different kinds of printing messages are sent during rendering:

The QuickDraw GX default implementations of the imaging messages provide the basic imaging functionality. You generally override some of these messages to manage the specifics of your device. Although you can override any of the messages to customize your driver, you often only need to override the GXSetupImageData universal imaging message to initialize your device, and then override some of the messages specific to the imaging system to handle your device.

If you are developing a printer driver for a PostScript device, you can likely use the default implementations for many PostScript devices, whereas you usually have to override the raster and vector imaging messages to generate the unique data sequences required by each raster and vector device.

You can find a complete description of the interface and functionality of each of the imaging messages in the chapter "Printing Messages" in this book.

Communicating With the Printing Device

During the device communications phase of printing, QuickDraw GX sends the data that composes the rendered form of each page to the printing device. This phase takes place in the background and is the phase during which physical communications with your device takes place.

Note
The device communications phase of printing can take place on a different computer than the computer on which imaging takes place. You need to keep this in mind when writing your code. For example, the code that you use to access a file during this phase needs to take this fact into account.
QuickDraw GX normally handles device communications with these operations:

The QuickDraw GX default implementations of the device communications messages handle communicating with your printing device for you. QuickDraw GX provides different versions of these messages for the different kinds of standard I/O: serial, Printer Access Protocol (PAP), or not-connected. You specify the communications type of your printing device in your driver resources, as described in the chapter "Printing Resources" in this book.

You override the printing device communications messages when you need to
customize the handling of the communication. For example, you can override the GXOpenConnection message to verify that a printing device of your type is connected to the computer and that the printing device is working properly. If you are writing a driver to capture printer output and store it in a file rather than directly communicate
it to a printing device, you can override the GXBufferData message and store the buffered data in a file. If you need to modify the primitive I/O handling for your printing device, you can override the GXWriteData message.

You usually forward these messages after adding your own instructions about handling them. If you choose to create your own communications buffering scheme, you can totally override the GXBufferData, GXDumpBuffer, and GXFreeBuffer messages.

You can find a complete description of the interface and functionality of each of the printing device communications messages in the section "Device Communications Messages" beginning on page 4-131 in the chapter "Printing Messages."

Interfacing With the Finder

The Macintosh Finder sends five messages that you might need to override in your driver: GXGetDTPMenuList, GXDTPMenuSelect, GXInitializeStatusAlert, GXHandleAlertEvent, and GXHandleAlertFilter. You override these messages to add any items to the Printing menu of the Finder and to handle events that occur in those items.

You can find a complete description of the interface and functionality of each of these Printing menu messages in the section "Finder Menu Messages" beginning on page 4-169 in the chapter "Printing Messages." Desktop printers and the menu choices associated with them are described in Inside Macintosh: QuickDraw GX Printing.

Providing a Chooser Interface

You need to make it possible for the user to choose your driver in the Chooser and to set any options that you provide, including various possibilities for communicating with your printing device, such as port options and baud rates.

You specify the connection possibilities for your driver in a look ('look') resource, which is used by the Chooser to display choices to the user. The look resource references the communications ('comm') resources that you provide, which allows QuickDraw GX to configure the device communications after the user makes a selection. The look and communications resources are discussed in the section "Using Resources in Drivers" beginning on page 3-53 and are described in detail in the chapter "Printing Resources"
in this book.

You also need to define Chooser package ('PACK') and list definition ('LDEF') resources for the Finder interface to your printer driver, just as you do for any other Macintosh driver. These resources are described in the Finder interface chapter in Inside Macintosh: More Macintosh Toolbox.

Handling Status and Alert Conditions

During the device communications phase of printing, you need to provide status information to the user through the Finder, and you need to handle error or alert conditions that occur on your printing device.

Status information is displayed in the desktop printer window, which is provided by the Finder. While your printer driver is handling the printing of a job, you update the status information that is displayed in this window with text strings such as "Downloading fonts to printer" or "Opening connection."

When a user is printing on a network with a print server, two copies of your driver are
in use at the same time: one on the computer on which the user initiated printing (the client), and another on the server that is connected to the printing device. Several user machines can be communicating with the print server simultaneously, so the Finder arbitrates which status information is sent to which driver on which user machine.

In status ('stat') resources that you include with your driver, you define the status text. When you want to display status information to the user, you call the GXReportStatus function, including the ID of the status text that you want shown. The Finder receives the status information from the GXReportStatus function and sends a GXWriteStatusToDTPWindow message to the copy of your driver that is running on the machine that initiated printing. The default implementation of the GXWriteStatusToDTPWindow message converts the status text ID into a string (by accessing the resource) and calls the GXWriteDTPData function to display the string.

Figure 3-1 shows the display of a status text string in the desktop printer window.

Figure 3-1 The printing status displayed in a desktop printer window

You can override the GXWriteStatusToDTPWindow message if you need to add information to the status text string at run time. For example, if you are composing a status text string that includes the current page number, you could override this message. In your override, you would determine if the current status text string is the one that you want to change, and produce a text string that incorporates the page number into it.

You need to alert the user when certain conditions arise during the printing of a document; for example, when the printing device runs out of paper, when the printing device requires that a sheet of paper be fed manually, or when a hardware error has occurred.

When these kinds of conditions occur, you have to alert the user, who then must take an action before printing can continue. The standard way to handle this is with a printing alert box. QuickDraw GX can manage displaying your printing alert box when you define printing alert ('plrt') resources. These resources automate the creation and display of alert boxes.

You implement handling of a printing alert box with the GXAlertTheUser function,
as described in the chapter "Printing Functions for Message Overrides" in this book. An example of using the GXAlertTheUser function is shown in Listing 3-15 on page 3-42.

You can find a complete description of the interface and functionality of each of the status and error-handling messages in the chapter "Printing Messages" in this book. You can find descriptions of the status and printing alert resources in the chapter "Printing Resources" in this book.

Providing Compatibility With the Macintosh Printing Manager

A final task to manage in your printer driver is how to interface to applications that use the Macintosh Printing Manager in the Macintosh Operating System. QuickDraw GX provides a default translation from Macintosh Printing Manager calls into QuickDraw GX messages, which allows those applications to use your printer driver without change.

You can customize this conversion with several resources. You can also override the default implementations of the Macintosh Printing Manager compatibility messages, which include such messages as GXPrOpenDoc, GXPrCloseDoc, GXPrOpenPage, GXPrJobInit, GXPrValidate, and GXPrJobMerge.

You can find a complete description of the interface and functionality of each of the Printing Manager compatibility messages in the section "Compatibility Messages" beginning on page 4-147 in the chapter "Printing Messages." You can find a description of the compatibility resources in the section "Resources Used for Printing Extensions and Printer Drivers" beginning on page 6-12 in the chapter "Printing Resources."

Subtopics
Writing Data to the Spool File
Reading Data From the Spool File
Converting QuickDraw GX Shapes
Communicating With the Printing Device
Interfacing With the Finder
Providing a Chooser Interface
Handling Status and Alert Conditions
Providing Compatibility With the Macintosh Printing Manager
Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996




Navigation graphic, see text links

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help